Table of Contents 


Introduction 


介绍 


文件 名 称 
文件 组 织 
缩 进 


注释 


空白 

命名 规范 
编程 惯例 
代码 示例 


Code Conventions for the Java 
Programming Language 中 文 翻译 《Java 编 
码 规 范 》 


Chinese translation of the Code Conventions for the Java Programming Language 
document. This document contains the standard conventions that we at Sun follow and 
recommend that others follow. It covers filenames, file organization, indentation, comments, 
declarations, statements, white space, naming conventions, programming practices and 
includes a code example. 


e 80% of the lifetime cost of a piece of software goes to maintenance. 

e Hardly any software is maintained for its whole life by the original author. 

e Code conventions improve the readability of the software, allowing engineers to 
understand new code more quickly and thoroughly. 


The last revision to this document was revised and updated on April 20, 1999 by Sun 
Microsystems. There is alse a GitBook version of the book: http://waylau.gitbooks.io/java- 
code-conventions/ or http://waylau.com/java-code-conventions/ Let's READ! 


(Java 编码 规范 》 中 文 翻译 。 这 个 文档 包含 了 Sun 所 遵循 以 及 推荐 的 标准 的 规范 。 它 涵盖 了 
文件 名 ， 文 件 组 织 ， 压 缩 ， 声 明 ， 注 释 ， 语 名 ， 空 白 ， 命 名 规范 ， 编 码 惯 例 以 及 一 个 代码 示 
例 o 

。 一 个 软件 的 生命 周期 中 ，80% 的 花费 用 于 维护 . 


© 几乎 没有 任何 一 个 软件 ， 在 其 整个 生命 周期 中 ， 均 由 最 初 的 作者 来 维护 . 
© 编码 规范 可 以 改善 软件 的 可 读 性 ， 可 以 让 程序 员 尽 快 而 彻底 地 理解 新 的 代码 . 


文档 最 后 版 本 由 Sun 公司 于 1999 年 4 月 20 日 更 新 ， 虽 然 过 去 十 几 年 ， 但 这 个 规范 至 今 对 编码 
的 规范 指导 仍然 适用 ， 特 此 翻译 。 如 有 勘误 欢迎 指正 。 


从 目录 开始 阅读 吧 


Get Started 如 何 开 始 阅 读 
选择 下 面 入 口 之 一 : 


e https://github.com/waylau/java-code-conventions 的 SUMMARY.md (源码 ) 

e http://waylau.gitbooks.io/java-code-conventions 点 击 Read 按钮 (同步 更 新 ， 国 内 访问 
速度 一 般 ) 

e http://waylau.com/java-code-conventions (国内 访问 速度 快 ， 定 期 更 新 。 最 后 更 新 于 
2017-8-31) 


oduction 
Issue 意见 、 建 议 
如 有 勘误 、 意 见 或 建议 欢迎 拍 砖 https://github.com/waylau/java-code-conventions/issues 


Contact 联系 作者 : 


Blog: waylau.com 
e Gmail: waylau521(at)gmail.com 
e Weibo: waylau521 


Twitter: waylau521 


Github : waylau 


1.1 为 啥 要 有 编码 规范 


对 于 编程 人 员 来 说 ， 编 码 规范 的 重要 性 体现 在 以 下 几 个 方面 : 


© 一 个 软件 的 生命 周期 中 ，80% 的 花费 用 于 维护 . 

© 几乎 没有 任何 一 个 软件 ， 在 其 整个 生命 周期 中 ， 均 由 最 初 的 作者 来 维护 . 

o 编码 规范 可 以 改善 软件 的 可 读 性 ， 可 以 让 程序 员 尽 快 而 彻底 地 理解 新 的 代码 . 

© 如 果 你 把 你 的 源 代码 作为 一 个 产品 ， 你 要 确保 它 是 否 被 很 好 的 打包 并 且 清 晰 无 误 ， 就 像 
你 已 构建 的 其 它 任何 产品 一 样 . 


1.2 致谢 


本 文档 反映 的 是 Sun MicroSystems 公司 Java Language Specification (Java 语 言 规范 ) 中 
的 编码 标准 部 分 ,主要 贡献 者 有 Peter King, Patrick Naughton, Mike DeMoney, Jonni Kanerva, 
Kathy Walrath, 和 Scott Hommel. 
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2 -文件 名 称 


这 部 分 列 出 了 常用 的 文件 名 及 其 后 缓 


2.1 文件 后 级 


Java 软件 使 用 下 面 文件 后 组 : 


文件 类 别 后 组 
Java 源 文 件 java 


Java 字 节 码 .Class 


2.2 常见 文件 名 称 


常见 文件 名 称 包 括 : 


文件 名 称 用 法 
GNUmakefile makefiles 的 首选 文件 名 。 我 们 使 用 gnumake 来 构建 软件 . 
README 概述 特定 目录 下 所 含 内 容 的 文件 的 首选 文件 名 . 
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一 个 文件 由 被 空 行 分 割 而 成 的 段落 以 及 标识 每 个 段落 的 可 选 注释 共同 组 成 。 
超过 2000 行 的 程序 难以 阅读 ， 应 该 尽量 避免 。 


正确 编码 格式 的 范例 ， 见 "Java 源 文件 案例 ". 


3.1 Java JR x 4 

每 个 Java 源 文件 都 包含 一 个 单一 的 公共 类 或 接口 。 若 私有 类 和 接口 与 一 个 公共 类 相关 联 ， 可 
以 将 它们 和 公共 类 放 入 同一 个 源 文 件 。 公 共 类 必须 是 这 个 文件 中 的 第 一 个 类 或 接口 。 

Java 源 文 件 还 遵循 以 下 规则 : 


eo 开头 注释 
e 包 和 引入 语句 
e 类 和 接口 声明 


3.1.1 开头 注释 


所 有 的 源 文 件 都 应 该 在 开头 有 一 个 C 语 言 风格 的 注释 ， 其 中 列 出 类 名 、 版 本 信息 、 日 期 和 版 权 
声明 : 


* Classname 
* Version information 
* Date 


* Copyright notice 


3.1.2 包 和 引入 语句 


在 多 数 Java 源 文件 中 ， 第 一 个 非 注释 行 是 package 语句 。 在 它 之 后 可 以 跟 import #4 ° 
例如 : 


package java.awt; 


import java.awt.peer.CanvasPeer; 


3.1.3 类 和 接口 声明 


下 表 描 述 了 类 和 接口 声明 的 各 个 部 分 以 及 它们 出 现 的 先后 次 序 。 见 "Java HIRA" 一 个 包 
含 注 释 的 例子 . 


class/interface 声明 注解 
的 各 个 部 分 


class/interface 文档 i E. 
、 LLI by 5 n" 
注释 (PETA) ede ete 


class 或 interface 
声明 


o 该 注释 应 包含 任何 有 关 整 个 类 或 接口 的 信息 ， 而 这 些 信息 又 不 适 
人 


A K j T #4 JE FR 
果 有 必要 的 话 合作 为 class/interface 文档 注释 


class ( static ) 变量 先是 public class 变量 ， 接 着 是 protected ， 再 是 包 级 别 ( 没 
i 有 访问 修饰 符 )， 再 是 private 。 


wg 先是 public class 变量 ， 接 着 是 protected ， 再 是 包 级 别 ( 没 
有 访问 修饰 符 ) ， 再 是 private ° 


这 些 方法 应 该 按 功能 ， 而 非 作 用 域 或 访问 权限 分 组 。 例 如 ， 一 个 
方法 私有 的 类 方法 可 以 置 于 两 个 公有 的 实例 方法 之 间 ， 其 目的 是 为 了 
更 便于 阅读 和 理解 代码 。 
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4 - 4a 2 


4 个 空格 常 被 作为 缩 进 排版 的 一 个 单位 。 本 文档 并 没有 规定 缩 进 的 实现 方式 (可 以 使 用 空格 或 
者 Tab 建 )。 如 果 使 用 Tab， 则 Tab 设 置 为 8 个 空格 (而 非 4 个 )。 


EAE: 不 同 的 IED 或 者 文本 编辑 器 中 ，Tab 的 空格 数 是 不 同 的 ， 常 见 的 有 4 格 或 者 8 格 。 所 

以 ， 这 个 文档 中 ， 如 果 强 调 了 使 用 Tab 刍 来 缩 进 ， 意 味 着 宝 了 8 格 。 否 则 ， 直 接 说 明 空 了 几 个 
格 ， 不 然 ， 会 产生 歧义 。 至 于 为 什么 是 8 格 ， 我 个 人 理解 ， 这 个 规范 应 该 是 参考 C 语言 规范 而 
来 。 一 般 不 建议 用 Tab 键 来 代替 空格 ， 除 非 整 个 团队 都 有 一 致 的 开发 工具 或 者 编码 格式 文件 。 


Zo Vp > 
4.1 TKE 
尽量 避免 一 行 的 长 度 超 过 80 个 字符 ， 因 为 很 多 终端 和 工具 不 能 很 好 处 理 。 


注意 : 用 于 文档 中 的 例子 应 该 使 用 更 短 的 行 长 ， 长 度 一 般 不 超过 70 个 字符 。 


4.2 换行 


当 一 个 表达 式 无 法 容纳 在 一 行内 时 ， 可 以 依据 如 下 一 般 规 则 断 开 : 


e 在 一 个 运 号 后 面 断 开 

© 在 一 个 操作 符 前 面 断 开 

。 宁可 选择 较 高 级 别 (higher-level) 的 断 开 ， 而 非 较 低级 别 (lower-level) 的 断 开 

© 新 的 一 行 应 该 与 上 一 行 同一 级 别 表达 式 的 开头 处 对 齐 

e 如 果 以 上 规则 导致 你 的 代码 混乱 或 者 使 你 的 代码 都 堆 挤 在 右边 ， 那 就 代 之 以 缩 进 8 个 空 
格 。 


以 下 是 断 开 方法 调用 的 一 些 例 子 : 


someMethod(longExpression1, longExpression2, longExpression3, 
longExpression4, longExpression5) ; 


var = someMethod1(longExpression1, 
someMethod2(longExpression2, 
longExpression3) ); 


以 下 是 两 个 断 开 算术 表达 式 的 例子 。 前 者 更 好 ， 因 为 断 开 处 位 于 括号 表达 式 的 外 边 ， 这 是 个 
较 高 级 别 的 断 开 。 


longName1 = longName2 * (longName3 + longName4 - longName5) 
+ 4 * longname6; // 推荐 


longNamei = longName2 * (longName3 + longName4 
- longName5) + 4 * longname6; // 避免 


oy 


以 下 是 两 个 缩 进 方法 声明 的 例子 。 前 者 是 常规 情形 。 后 者 如 果 按 照常 规 的 缩 进 方法 就 会 使 得 


第 二 行 和 第 三 行 太 靠 右边 ， 所 以 只 缩 进 8 个 字符 。 


// 常 规 缩 进 
someMethod(int anArg, Object anotherArg, String yetAnotherArg, 
Object andStillAnother) { 





// 缩 进 8 个 省 进 的 太 深 
private static synchronized horkingLongMethodName(int anArg, 
Object anotherArg, String yetAnotherArg, 


Object andStillAnother) { 


if 语句 的 换行 通常 使 用 8 个 空格 的 规则 ， 因 为 常规 缩 进 (4 个 空格 ) 会 使 语句 体 看 起 来 比较 费 
劲 。 比 如 : 


// 不 要 使 用 这 种 

If ((condition1 && condition2) 
|| (condition3 && condition4) 
||!(condition5 && condition6)) { //BAD WRAPS 
doSomethingAboutIt(); //MAKE THIS LINE EASY TO MISS 


// 用 这 个 来 代替 
If ((condition1 && condition2) 
|| (condition3 && condition4) 
| |!(condition5 && condition6)) { 
doSomethingAboutIt(); 


// 或 用 这 种 
if ((condition1 && condition2) || (condition3 && condition4) 
||!(condition5 && condition6)) { 
doSomethingAboutIt(); 


这 里 有 三 种 可 行 的 方法 用 于 处 理 三 元 运算 表达 式 : 


alpha = (aLongBooleanExpression) ? beta : gamma; 


alpha = (aLongBooleanExpression) ? beta 
: gamma; 


alpha = (aLongBooleanExpression) 


? beta 


: gamma; 
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5 - 注释 


Java 有 两 类 注释 :implementation comments (实现 注释 ) 和 documentation comments ( 文 

档 注 释 ) 。 实 现 注释 常见 于 C++， 使 用 /*...*/ 和 // 。 文 档 注 释 (也 称 为 "doc 

comments") 是 Java 独 有 的 ， 使 用 /**...*/ 。 文 档 注 释 可 以 通过 javadoc 工具 转 成 HTML 

文件 。 

实现 注释 用 以 注释 代码 或 者 特殊 的 实现 。 文档 注释 从 implementation-free ( 实 由 ) 的 角度 
阁 述 代码 的 规范 。 它 可 以 被 那些 手头 没有 源码 的 开发 人 员 读 懂 。 

注释 应 被 用 来 给 出 代码 的 总 览 ， 并 提供 代码 自身 没有 提供 的 附加 信息 。 注 释 应 该 仅 包含 与 阅 

读 和 理解 程序 有 关 的 信息 。 例 如 ， 相 应 的 包 如 何 被 建立 或 位 于 哪个 目录 下 之 类 的 信息 不 应 包 

括 在 注释 中 。 

在 注释 里 ， 对 设计 决策 中 重要 的 或 者 不 是 显而易见 的 地 方 进 行 说 明 是 可 以 的 ， 但 应 避免 提供 

代码 中 己 清晰 表达 出 来 的 重复 信息 。 多 余 的 的 注释 很 容易 过 时 。 通 常 应 避免 那些 代码 更 新 就 

可 能 过 时 的 注释 。 

注意 : 频繁 的 注释 有 时 反映 出 代码 的 低 质 量 。 当 你 觉得 被 迫 要 加 注释 的 时 候 ， 考 虑 一 下 重 写 代 

码 使 其 更 清晰 。 

注释 不 应 写 在 用 星 号 或 其 他 字符 画 出 来 的 大 框 里 。 


注释 不 应 包括 诸如 制 表 符 和 回 退 符 之 类 的 特殊 字符 。 


5.1 实现 注释 的 格式 

实现 注释 的 格式 主要 有 4 种 : block ( 块 ) , single-line (单行 ) , trailing ( 尾 端 ) ,和 end-of- 
line《〈 行 末 ) . 

5.1.1 块 注释 


块 注 释 通常 用 于 提供 对 文件 ， 方 法 ， 数 据 结 构 和 算法 的 描述 。 块 注释 被 置 于 每 个 文件 的 开始 
处 以 及 每 个 方法 之 前 。 它 们 也 可 以 被 用 于 其 他 地 方 ， 比 如 方法 内 部 。 在 功能 和 方法 内 部 的 块 
注释 应 该 和 它们 所 描述 的 代码 具有 一 样 的 缩 进 格式 。 


块 注释 之 首 应 该 有 一 个 空 行 ， 用 于 把 块 注释 和 代码 分 割 开 来 ， 比 如 : 


/* 


* 


Here is a block comment. 
*/ 


块 注释 可 以 以 /- 开 头 ， 这 样 indent(1) 就 可 以 将 之 识别 为 一 个 代码 块 的 开始 ， 而 不 会 重 排 它 。 


* Here is a block comment with some very special 


* 


formatting that I want indent(1) to ignore. 


* 


one 


Note: 如 果 你 不 使 用 indent(1)， 就 不 必 在 代码 中 使 用 /*-， 或 为 他 人 可 能 对 你 的 代码 运行 
indent(1) 作 让 步 。 详 见于 5.2 节 "Documentation Comments" 
5.1.2 单行 注释 


短 注 释 可 以 显示 在 一 行内 ， 并 与 其 后 的 代码 具有 一 样 的 缩 进 层级 。 如 果 一 个 注释 不 能 在 一 行 
内 写 完 ， 就 该 采用 块 注释 (参见 "5.1.1 块 注释 ")。 单 行 注释 之 前 应 该 有 一 个 空 行 。 以 下 是 一 个 
Java 代码 中 单行 注释 的 例子 : : 


if (condition) { 


/* Handle the condition. */ 


5.1.3 尾 端 注释 


极 短 的 注释 可 以 与 它们 所 要 描述 的 代码 位 于 同一 行 ， 但 是 应 该 有 足够 的 空白 来 分 开 代 码 和 注 
释 。 若 有 多 个 短 注释 出 现 于 大 段 代 码 中 ， 它 们 应 该 具有 相同 的 缩 进 。 


以 下 是 一 个 Java 代 码 中 尾 端 注释 的 例子 : 


imes) 


return TRUE; /* special case */ 
} else { 
return isPrime(a); /* works only for odd a */ 
} 
s- R L: 
5.1.4 行 末 注 释 


注释 界定 符 // ， 可 以 注释 掉 整 行 或 者 一 行 中 的 一 部 分 。 它 一 般 不 用 于 连续 多 行 的 注释 文 
本 ; 然而 ， 它 可 以 用 来 注释 掉 连 续 多 行 的 代码 段 。 以 下 是 所 有 三 种 风格 的 例子 : 


if (foo > 1) { 
// Do a double-flip. 


} 


else 
return false; // Explain why here. 
Hi/seip oeie = aby) 4h 
V 
// // Do a triple-flip. 
Md 
//} 
//else 
Hi return false; 


5.2 文档 注释 
注意 : 此 处 描述 的 注释 格式 之 范例 ， 参 见 "Java 源 文件 范例 "。 


更 多 细节 ， 详 见 "How to Write Doc Comments for Javadoc"， 里 面包 含 了 文档 注释 标签 的 信 
息 (@return, @param, @see): 


链接 
更 多 关于 文档 注释 和 javadoc， 详 见 javadoc 主页 
这 里 


文档 注释 描述 Java 的 类 、 接 口 、 构 造 器 ， 方 法 ， 以 及 字段 (field)。 每 个 文档 注释 都 会 被 置 于 
注释 定 界 符 ey 之 中 ， 一 个 注释 对 应 一 个 类 、 接 口 或 成 员 。 该 注释 应 位 于 声明 之 前 : 


/** 

* The Example class provides ... 
‘7, 

public class Example { 


} 
注意 顶层 (top-level) 的 类 和 接口 是 不 缩 进 的 ， 而 其 成 员 是 缩 进 的 。 描 述 类 和 接口 的 文档 注释 
的 第 一 行 ( /** ) 不 需 缩 进 ; 随后 a 吏 星 号 纵向 对 齐 )。 成 员 ， 包 括 构 
造 函 数 在 内 ， 其 文档 注释 的 第 一 行 缩 进 4 格 ， 随 后 每 行 都 缩 进 5 格 。 


若 你 想 给 出 有 关 类 、 接 口 、 变 量 或 方法 的 信息 ， 而 这 些 信 息 又 不 适合 写 在 文档 中 ， 则 可 使 用 
实现 块 注释 ( 见 5.1.1) 或 紧 跟 在 声明 后 面 的 单行 注释 ( 见 5.1.2)。 例 如 ， 有 关 一 个 类 实现 的 细节 ， 
应 放 入 紧 跟 在 类 声明 后 面 的 实现 块 注释 中 ， 而 不 是 放 在 文档 注释 中 。 

文档 注释 不 能 放 在 一 个 方法 或 构造 器 的 定义 块 中 ， 因 为 Java 会 将 位 于 文档 注释 之 后 的 第 一 个 
声明 与 其 相关 联 。 
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6.1 每 行 声 明 变 量 的 数量 


推荐 一 行 一 个 声明 ， 因 为 这 样 以 利于 写 注 释 。 即 ， 


int level; // indentation level 
int size; // size of table 


要 优 于 


int level, size; 


不 要 将 不 同类 型 变量 的 声明 放 在 同一 行 ， 例 如 : 


int foo, fooarray[]; // ‘ix! 


注意 : 上 面 的 例子 中 ， 在 类 型 和 标识 符 之 间 放 了 一 个 空格 ， 另 一 种 被 允许 的 替代 方式 是 使 用 制 
表 符 : 


int level; // indentation level 
int size; // size of table 
Object currentEntry; // currently selected table entry 


6.2 初始 化 


尽量 在 声明 局 部 变量 的 同时 初始 化 。 唯 一 不 这 么 做 的 理由 是 变量 的 初始 值 依赖 于 菜 些 先前 发 
生 的 计算 。 


6.3 布局 


只 在 代码 块 的 开始 处 声明 变量 。 (一 个 块 是 指 任何 被 包含 在 大 括号 { 和 } 中 间 的 代码 。) 
不 要 在 首次 用 到 该 变量 时 才 声 明之 。 这 会 把 注意 力 不 集 中 的 程序 员 搞 糊 涂 ， 同 时 会 妨碍 代码 


在 该 作用 域内 的 可 移植 性 。 


void myMethod() { 


int int1 = 0; // beginning of method block 


if (condition) { 


int int2 = 0; // beginning of "if" block 


该 规则 的 一 个 例外 是 for 循 环 的 索引 变量 : 


for (int i = 0; i < maxLoops; i++) { ... } 


避免 声明 的 局 部 变量 履 盖 上 一 级 声明 的 变量 。 例 如 ， 不 要 在 内 部 代码 块 中 声明 相同 的 变量 名 : 


int count; 


myMethod() { 
if (condition) { 
int count = 0; // 避免 


6.4 类 和 接口 的 声明 
当 编写 关 和 接口 是 ， 应 该 遵守 以 下 格式 规则 : 


© 在 方法 名 与 其 参数 列表 之 前 的 左 括 号 ( 间 不 要 有 空格 
e 左 大 括号 { 位 于 声明 语句 同行 的 末尾 
© 右 大 括号 } 另 起 一 行 ， 与 相应 的 声明 语 多 对齐， 除非 是 一 个 


后 


空 语句 ，} 应 紧 跟 在 { 之 


xa 


class Sample extends Object { 
int ivari; 
int ivar2; 
Sample(int i, int j) { 
ivari = i; 
ivar2 = j; 


int emptyMethod() {} 


© 方法 与 方法 之 间 以 空 行 分 隔 
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7-8 4 


7.1 简单 语句 


argv++; 
argce--; 


argv++; argc--; // 


7.2 复合 语句 


复合 语句 是 包含 在 大 括号 中 的 语句 序列 ， 形 如 { statements } 。 例 如 下 面 各 段 。 


。 被 括 其 中 的 语句 应 该 较 之 复合 语句 缩 进 一 个 层次 
。 左 大 括号 "(" 应 位 于 复合 语句 起 始 行 的 行 尾 ; 右 大 括号 中 应 另 起 一 行 并 与 复合 语句 首 行 对 


齐 。 
© 大 括号 可 以 被 用 于 所 有 语句 ， 包 括 单个 语句 ， 只 要 这 些 语句 是 诸如 if-else 或 for 控 
制 结构 的 一 部 分 。 这 样 便于 添加 语句 而 无 需 担 心 由 于 忘 了 加 括号 而 引入 bug 。 


7.3 return 语句 


一 个 带 返 回 值 的 return 语句 不 使 用 小 括号 "()"， 除 非 它 们 以 某 种 方式 使 返回 值 更 为 显 见 。 例 
如 : 


return; 
return myDisk.size(); 


return (size ? size : defaultSize); 


7.4 if, if-else, if else-if else 74 4) 


if-else 语句 应 该 是 以 下 形式 : 


if (condition) { 


statements; 
} 
if (condition) { 
statements; 
} else { 
statements; 


} 


if (condition) { 
statements; 

} else if (condition) { 
statements; 

} else { 
statements; 


} 


注意 : if 语句 通常 使 用 G 。 避 免 下 面容 易 出 错 的 形式 : 


if (condition) // 避免 ! 这 省 略 了 括号 


cn 
Ww 


statement; 


7.5 for 72 4) 


for 语句 应 该 是 如 下 形式 : 


for (initialization; condition; update) { 
statements; 


} 


空 的 for 语句 (所 有 工作 都 在 初始 化 ， 条 件 判断 ， 更 新 子 句 中 完成 ) 应 该 是 如 下 形式 : 


for (initialization; condition; update); 


% A forié 4) 4) 4S URS HF A] PRA HY  BRARAASULES? MHRAZRRR 
高 。 若 需要 ， 可 以 在 for 循环 之 前 (为 初始 化 子 句 ) 或 for 循环 末尾 (为 更 新 子 包 ) 使 用 单独 的 语 
aJ o 


7.6 while 7 4) 


while 语句 应 该 是 如 下 形式 : 


while (condition) { 
statements; 


空 的 while 语句 应 该 是 如 下 形式 : 


while (condition); 


7.7 do-while +2 4 


do-while 语句 应 该 是 如 下 形式 : 


do { 
statements; 
} while (condition); 


7.8 switch 74 4 


switch 语 a] 应 该 是 如 下 形 Ñ: 


switch (condition) { 

case ABC: 
statements; 
/* falls through 

case DEF: 
statements; 
break; 

case XYZ: 
statements; 
break; 

default: 
statements; 
break; 


每 当 一 个 case 顺 着 往 下 执行 时 (因为 没有 break 语句 )， 通 常 应 在 break 语句 的 位 置 添加 注 
释 。 上 面 的 示例 代码 中 就 包含 注释 /* falls through */ ° 


Every switch statement should include a default case. The break in the default case is 
redundant, but it prevents a fall-through error if later another case is added. 


7.9 try-catch 7 4) 


try-catch 语句 应 该 是 如 下 格式 : 


try { 
statements; 

} catch (ExceptionClass e) { 
statements; 


} 


一 个 try-catch 语句 后 面 也 可 能 跟着 一 个 finally 4) > Ke try 代码 块 是 否 顺利 执行 完 ， 
它 都 会 被 执行 。 


try { 
statements; 

} catch (ExceptionClass e) { 
statements; 

} finally { 
statements; 


} 
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室 行 将 逻辑 相关 的 代码 段 分 隔 开 ， 以 提高 可 读 性 。 
下 列 情 况 应 该 总 是 使 用 两 个 空 行 : 


e 一 个 源 文 件 的 两 个 片段 之 问 
。 类 声明 和 接口 声明 之 问 


下 列 情况 应 该 总 是 使 用 一 个 空 行 : 


e 两 个 方法 之 间 

© 方法 内 的 局 部 变量 和 方法 的 第 一 条 语句 之 间 

© 块 注释 (参见 "5.1.1 节 ") 或 单行 注释 (参见 "5.1.2 节 ") 之 前 
e 一 个 方法 内 的 两 个 逻辑 段 之 间 ， 用 以 提高 可 读 性 


下 列 情 况 应 该 使 用 空格 : 


© 一 个 紧 跟 着 括号 的 关键 字 应 该 被 空格 分 开 ， 例 如 : 


while (true) { 


} 


注意 : 空格 不 应 该 置 于 方法 名 与 其 左 括号 之 间 。 这 将 有 助 于 区 分 关键 字 和 方法 调用 。 

。 空格 应 该 位 于 参数 列表 中 带 号 的 后 面 

。 所 有 的 二 元 运算 符 ， 除 了 . ， 应 该 使 用 空格 将 之 与 操作 数 分 开 。 一 元 操作 符 和 操作 数 之 
间 不 因 该 加 空格 ， 比 如 : 负 号 ( - )、 自 增 ( ++ ) 和 自 减 ( -- )。 例 如 : 


a += c +d; 
a= (a + b) / (c * d); 


while (d++ = s++) { 
n++; 


了 


} 


printSize("size is " + foo + "\n"); 


。 for 语句 中 的 表达 式 应 该 被 空格 分 开 ， 例 如 : 


for (expr1; expr2; expr3) 


o 强制 转型 后 应 该 跟 一 个 空格 ， 例 如 : 


myMethod((byte) aNum, (Object) x); 
myMethod((int) (cp + 5), ((int) (i + 3)) + 1); 
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9 -命名 规范 


命名 规范 使 程序 更 易 读 ， 从 而 更 易于 理解 。 它 们 也 可 以 提供 一 些 有 关 标 识 符 功能 的 信息 ， 以 
助 于 理解 代码 ， 例 如 ， 不 论 它 是 一 个 常量 ， 包 ， 还 是 类 


包 
(Packages) 


类 


(Classes) 


接口 
(Interfaces) 


方法 
(Methods) 


亦 2 
RE 


(Variables) 


实例 变量 
(Instance 
Variables) 


常量 
(Constants) 


命名 规则 


一 个 唯一 包 名 的 前 组 总 是 全 部 小 写 的 ASCII 
字母 并 且 是 一 个 顶级 域名 ， 通 常 是 com ， 
edu，gov，mil，net，org， 或 1981 年 ISO 
3166 标 准 所 指定 的 标识 国家 的 英文 双 字 符 代 
码 。 包 名 的 后 续 部 分 根据 不 同 机 构 各 自 内 部 
的 命名 规范 而 不 尽 相 同 。 这 类 命名 规范 可 能 
以 特定 目录 名 的 组 成 来 区 分 部 门 
(department)， 项 目 (project)， 机 器 
(machine)， 或 注册 名 (login names) ° 


命名 规则 : 类 名 是 个 一 名 词 ， 采 用 大 小 写 混 
合 的 方式 ， 每 个 单词 的 首 字 母 大 写 。 尽 量 使 
你 的 类 名 简洁 而 富 于 描述 。 使 用 完整 单词 ， 
避免 缩写 词 (除非 该 缩写 词 被 更 广泛 使 用 ， 像 
URL > HTML) 


命名 规则 : 大 小 写 规则 与 类 名 相似 


方法 名 是 一 个 动词 ， 采 用 大 小 写 混合 的 方 
式 ， 第 一 个 单词 的 首 字母 小 写 ， 其 后 单词 的 
首 字母 大 写 。 


除了 变量 名 外 ， 所 有 实例 ， 包 括 类 ， 类 常 
量 ， 均 采用 大 小 写 混 合 的 方式 ， 第 一 个 单词 
的 首 字母 小 写 ， 其 后 单词 的 首 字母 大 写 。 变 
量 名 不 应 以 下 划 线 或 美元 符号 开头 ， 尽 管 这 
在 语法 上 是 允许 的 。 变 量 名 应 简短 且 富 于 描 
述 。 变 量 名 的 选用 应 该 多 于 记忆 ， 即 ， 能 够 
指出 其 用 途 。 尽 量 避 免 单个 字符 的 变量 名 ， 
除非 是 一 次 性 的 临时 变量 。 临 时 变量 通常 被 
取 名 为 i，j，k ，m 和 n ， 它 们 一 般 
用 于 整 型 ; c ，d ，e ， 它 们 一 般 用 于 字 
符 型 。 


大 小 写 规则 和 变量 名 相似 ， 除 了 前 面 需要 一 
ANF x] Bi 


类 常量 和 ANSI 常 量 的 声明 ， 应 该 全 部 大 写 ， 
单词 间 用 下 划 线 陋 开 。( 尽 量 避免 ANSI 党 
量 ， 容 易 引起 错误 ) 


com.sun.eng 
com.apple.quicktime.v2 
edu.cmu.cs.bovik.cheese 


Class Raster class 


ImageSprite 


interface 
RasterDelegate 
interface Storing 


run() runFast() 
getBackground() 


char c int i float 
myWidth 
int _employeeId String 


_name Customer 
_customer 


static final int 


MIN_WIDTH = 4 static 
final int MAX_WIDTH = 


999 static final int 
GET_THE_CPU = 1 
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10 - 编程 惯例 


10.1 提供 对 实例 以 及 类 变量 的 访问 


如 果 没 有 充分 理由 ， 不 要 设置 实例 或 者 类 变量 为 public。 通 常 实例 变量 无 需 显 式 的 set( 设 置 ) 和 
gotten( 获 取 )， 通 常 这 作为 方法 调用 的 side effect (边缘 效应 ) 而 产生 。 


一 个 具有 public 实例 变量 的 恰当 例子 是 ， 类 仅 作 为 数据 结构 ， 没 有 行为 。 即 ， 若 你 要 使 用 一 
个 struct (结构 ) 而 非 一 个 类 (如 果 java 支 持 struct 的 话 )， 那 么 把 类 的 实例 变量 声明 为 
public 是 合适 的 。 


10.2 引用 类 变量 和 类 方法 


避免 用 一 个 对 象 访问 一 个 类 的 ( static) 变量 和 方法 。 应 该 用 类 名 替代 。 例 如 


classMethod(); // OK 
AClass.classMethod(); // OK 
anObject.classMethod(); // sR! 


10.3 第 量 


位 于 for 循环 中 作为 计数 器 值 的 数字 常量 ， 除 了 -1 ,9 和 1 之 外 ， 不 应 被 直接 写 入 代码 。 
10.4 变量 赋值 
避免 在 一 个 语 多 中 给 多 个 变量 赋 相 同 的 值 。 它 很 难 读 懂 。 例 如 
fooBar.fChar = barFoo.lchar = 'c'; // #9 
不 要 将 赋值 运算 符 用 在 容易 与 相等 关系 运算 符 混淆 的 地 方 。 例 如 : 


if (c++ = d++) { 


} 


if ((c++ = d++) != 0) { 


} 


不 要 使 用 内 上 或 (embedded) 赋 值 运算 符 试图 提高 运行 时 的 效率 ， 这 是 编译 器 的 工作 。 例 如 : 


doa bte) r; // 避免 ! 


a bD EEC 


d=a+r; 


10.5 其 它 惯例 


10.5.1 圆 括 号 


一 般 而 言 ， 在 含有 多 种 运算 符 的 表达 式 中 使 用 圆 括号 来 避免 运算 符 优 先 级 问题 ， 是 个 好 方 
法 。 即 使 运算 符 的 优先 级 对 你 而 言 可 能 很 清楚 ， 但 对 其 他 人 未 必 如 此 。 你 不 能 假设 别 的 程序 
员 和 你 一 样 清楚 运算 符 的 优先 级 。 


if (a == b @& c == d) // 避免 ! 
if ((a == b) && (c == d)) // 正确 


10.5.2 返回 值 


设法 让 你 的 程序 结构 符合 目的 。 例 如 : 


if (booleanExpression) { 
return true; 

} else { 
return false; 


} 


应 该 用 下 面 代替 


return booleanExpression; 


同 理 ， 


if (condition) { 
return x; 


} 


return y; 


return (condition ? x : y); 


10.5.3 条 件 运 算 符 ? 前 的 表达 式 


如 果 一 个 包含 二 元 运算 符 的 表达 式 出 现在 三 元 运算 符 ?: 的 ? 之前， 那么 应 该 给 表达 式 添 上 
一 对 圆 括号 。 例 如 : 


(x >= 0) ? x : -x; 


10.5.4 特殊 注解 


使 用 xxx 标识 处 代码 虽然 实现 了 功能 ， 但 是 实现 的 方法 有 待 商 榨 ， 希 望 将 来 能 改进 。 使 用 
FIXME 标识 处 代码 需要 修正 ， 其 至 代码 是 错误 的 ， 不 能 工作 ， 需 要 修复 。 
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11 - 代码 示例 


11.1 Java %. X4 T4] 


下 面 的 例子 ， 展 示 了 如 何 合理 布局 一 个 包含 单一 公共 类 的 Java 源 程序 。 接 口 的 布局 与 其 相 


似 。 更 多 信息 参见 "类 和 接口 声明 "and "文档 注释 " 


as 
* @(#)Blah.java 1.82 99/03/18 


* Copyright (c) 1994-1999 Sun Microsystems, Inc. 
* 901 San Antonio Road, Palo Alto, California, 94303, U.S.A. 
* All rights reserved. 


* This software is the confidential and proprietary information of Sun 
* Microsystems, Inc. ("Confidential Information"). You shall not 

* disclose such Confidential Information and shall use it only in 

* accordance with the terms of the license agreement you entered into 
* with Sun. 

tees 


package java.blah; 
import java.blah.blahdy.BlahBlah; 


JER 
* Class description goes here. 
* 
* @version 1.82 18 Mar 1999 
* @author Firstname Lastname 
ard 
public class Blah extends SomeClass { 
/* A class implementation comment can go here. */ 


/** classVari documentation comment */ 
public static int classVar1; 


on 
* classVar2 documentation comment that happens to be 
* more than one line long 
E26 

private static Object classVar2; 


/** instanceVari documentation comment */ 
public Object instanceVar1; 
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代码 示例 


/** instanceVar2 documentation comment */ 
protected int instanceVar2; 


/** instanceVar3 documentation comment */ 
private Object[] instanceVar3; 


[eres 
* ,..constructor Blah documentation comment... 
aif 
public Blah() { 
// ...implementation goes here... 
} 
fax 
* ,..method doSomething documentation comment... 
S/A 
public void doSomething() { 
yminmentat on Goes Neher. . 
} 
VEE 
* ,..method doSomethingElse documentation comment... 


* @param someParam description 
a 
public void doSomethingElse(Object someParam) { 
// fae UMP LEMentatLoneGoesmnenerrnn. 
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